Inside Macintosh: Open Transport /

Chapter 6 - Configuration Management / Configuration Management Reference

Functions / Requesting a Port to Yield Ownership

OTYieldPortRequest

Requests that a port be yielded.

C INTERFACE

OSStatus OTYieldPortRequest (ProviderRef provider, OTPortRef ref, 
                             OTClientList* buffer, size_t size); 

C++ INTERFACES

None. C++ applications use the C interface to this function.

PARAMETERS

provider

The provider reference for the provider that wants to use the port. This provider (normally an endpoint) must be open on the requested port. You cannot use this provider while the yield request is being processed.

ref

The port reference for the port you wish to use.

buffer

If the request is denied, on output this contains a pointer to a client list structure, giving the names of all clients that rejected the request (normally only one). You can use a value of NULL to force the client to yield the port; this only works if the provider is passively listening on the port. Use a value of (void*)-1L to cancel the yield request.

size

The size of the buffer, including the fNumClients field in the client list structure.

DESCRIPTION

The OTYieldPortRequest function requests the current owner of a port (normally a serial port or modem) to yield ownership of it. Open Transport sends the kOTYieldPortRequest event to each provider of any registered clients for that port for acceptance or denial. If the owner has not registered as a client of Open Transport, no event can be sent and acceptance is implicit.

If the function returns an error, the request could not be completed. This could be because the current owner refused to yield, in which case the error code provides the reason for the denial.This also could be because there is not enough memory (kENOMEMErr), the port does not support yielding (kOTNotSupportedErr), the provider does not use the port or the port does not exist (kOTBadReferenceErr), or because the current client is already connected (kENOENTErr).

Once the yield port request returns with an kOTNoError result code (or kENOENTErr, if the provider does not currently have a client), you can attempt to use the port. Normally you do this by binding with a queue length (qlen ) greater than 0, or by connecting. If you do not use the port or cancel the yield request within 10 seconds, the port automatically stops being available for your use and reverts to its original owner.

In the case of forcing the client to yield, if the function returns kOTNoError, then the port has been yielded, and you can use it. Note that you can only force a port to yield if its current client is passively listening; it cannot be yielded if a connection is in progress.

SPECIAL CONSIDERATIONS

The OTYieldPortRequest function is available only to PowerPC-native clients; there is no mixed-mode glue for the function, so you must build your application FAT in order to use it.

SEE ALSO

To register as a client, use the OTRegisterAsClient function (page 6-44).

The client list structure is described in "The Client List Structure" (page 6-22).